{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Qkit Sample Objects"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The sample objects are very general and basic objects in qkit. They can be used to **store any parameters of your current measurement sample**. Sample objects are used as default in some measurement scripts like timedomain measurements to reduce the number of parameters that is passed as arguments. \n",
    "\n",
    "The sample object can basically be seen as a dict, where you can store any information you want. This is particularly helpful if you write your own measurement notebook and want to apply it to different samples with different parameters. You can then simply exchange the loaded sample at the beginning of your notebook and leave the rest untouched."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Get started"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "QKIT configuration initialized -> available as qkit.cfg[...]\n"
     ]
    }
   ],
   "source": [
    "import qkit\n",
    "qkit.cfg['datadir'] = r'c:\\data'\n",
    "qkit.cfg['run_id'] = 'Run0'\n",
    "qkit.cfg['user'] = 'qkit_user'\n",
    "\n",
    "import qkit.measure.samples_class as sc"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "demo = sc.Sample()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We start by creating an empty sample, which only has *comment* and *name* as attributes.\n",
    "\n",
    "You can either use the `sample.get_all()` function to get a string of all attributes, or you directly use *sample.attribute* to access the attribute directly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "comment:   \n",
      "name:   Arbitrary Sample\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print demo.get_all()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Arbitrary Sample'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "demo.name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "demo.comment = \"This sample looks promising.\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Adding new attributes is easy, you can just set them:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "demo.frequency = 8e9"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "comment:   This sample looks promising.\n",
      "frequency:   8000000000.0\n",
      "name:   Arbitrary Sample\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print demo.get_all()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The sample class has also a get function, which can be used to set a default. (the same as in a dict)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "8000000000.0"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "demo.get('frequency',1e9)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "demo.get('current',0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Saving samples"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `save` function saves the full sample object into a JSON serialized file. You can pass a *filename* argument:\n",
    "* **None (default)**: save to datadir/ID.sample\n",
    "* **absolute filepath**: save to filepath\n",
    "* **any other string**: save to datadir/ID_string.sample\n",
    "\n",
    "Here, datadir is `qkit.cfg['datadir']` and ID is the measurement ID as it would be given for a regular measurement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'c:\\\\data\\\\Run0\\\\qkit_user\\\\P8PWYL.sample'"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "demo.save()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'c:\\\\data\\\\Run0\\\\qkit_user\\\\P8PWYL_sweet_spot.sample'"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "demo.save('sweet_spot')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "u'C:/Users/Public/qkitsample.sample'"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "demo.save(u'C:/Users/Public/qkitsample')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading samples"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can either use an existig sample with `sample.load(filename)` or generate a new sample `Sample(filename)`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "demo.load('Run0/qkit_user/P8PWYL.sample') # path can be specified relaive to the datadir"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "demo2 = sc.Sample(u'C:/Users/Public/qkitsample.sample') # absolute pathname is also fine"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Make sure to update all references if you create a new sample object or overwrite it. If you use the `load` function, the reference will stay the same."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.14"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
